Inside Macintosh: QuickDraw GX Graphics /

Chapter 5 - Bitmap Shapes / Using Bitmap Shapes

Applying Transformations to Bitmaps

Although bitmap shapes make limited use of their style and ink objects, they make full use of their transform objects. The examples in this section show how you can use the transform object of a bitmap to affect the drawing of that bitmap. The first few sample functions illustrate mapping transformations, and the last sample function illustrates clipping.

Mapping Bitmap Shapes

Since a bitmap geometry contains a pixel image rather than a geometric description, applying mapping transformations to bitmap shapes does not produce the same quality results as applying mapping transformations to geometric shapes. To use as an example, Figure 5-22 shows the path shape converted to a bitmap in Listing 5-9 on page 5-35.

Figure 5-22 A path shape converted to a bitmap shape

You can call the GXSkewShape function to undo the skewing of the figure-eight shape:

GXSkewShape(pathToBitmapShape, -fl(.1), -fl(.1), ff(60), ff(60));

Figure 5-23 shows the results of performing this transformation on the figure-eight bitmap shape.

Figure 5-23 A path shape converted to a bitmap shape and then skewed

As Figure 5-23 shows, the quality of the transformed bitmap has degraded due to the skewing. If the gxMapTransformShape shape attribute of the bitmap shape is not set, this degradation of quality becomes more pronounced with multiple transformations. For example, consider the color ramp depicted in Figure 5-24. For a color version of this figure, see Plate 4 at the front of this book.

Figure 5-24 A color ramp bitmap

The following lines of code clear the gxMapTransformShape shape attribute for this bitmap shape and then rotate the shape 360 times by 1 degree each time:

GXSetShapeAttributes(aColorRampBitmapShape,
                     GXGetShapeAttributes(aColorRampBitmapShape) 
                      & ~gxMapTransformShape);
for (count = 1; count <= 360; count ++)
   GXRotateShape(aColorRampBitmapShape, ff(1), ff(100), ff(100));

Enough error is introduced to create a interesting new bitmap, as shown in Figure 5-25. For a color version of this figure, see Plate 5 at the front of this book.

Figure 5-25 A bitmap after multiple transformations

However, if you leave the gxMapTransformShape shape attribute set, you can apply the same 360 transformations, and the resulting bitmap is identical to the original bitmap. In this case, all of the transformations affect the mapping matrix stored in the bitmap's transform object and not the pixel values of the bitmap's pixel image.

Scaling text provides another example of transformations degrading the quality with which QuickDraw GX draws a shape. As an example, the sample function in Listing 5-10 creates a text shape, draws it, scales it up, and then draws the scaled version. This sample function uses the GXScaleShape function, which is described in the chapter "Transform Objects" of Inside Macintosh: QuickDraw GX Objects.

Listing 5-10 Scaling text

void ScaleText(void)
{
   gxShape  aTextShape;
   const gxPoint initialLocation = {ff(50), ff(50)};


   aTextShape = GXNewText(9, (unsigned char *) "123456789",
                          &initialLocation) ;
   GXDrawShape(aTextShape);

   GXScaleShape(aTextShape, ff(3), ff(3), ff(0), ff(50));

   GXDrawShape(aTextShape);
   GXDisposeShape(aTextShape);
}

The result is shown in Figure 5-26.

Figure 5-26 Scaled text

If you convert the text shape to a bitmap shape before scaling it, as in the sample function in Listing 5-11, the result is quite different.

Listing 5-11 Scaling a bitmap

void ScalingABitmap(void)
{
   gxShape aBitmapShape;
   gxPoint initialLocation = {ff(50), ff(50)};


   aBitmapShape = GXNewText(9, (unsigned char *) "123456789",
                            &initialLocation) ;

   GXSetShapeType(aBitmapShape, gxBitmapType);

   GXDrawShape(aBitmapShape);

   GXScaleShape(aBitmapShape, ff(3), ff(3), ff(0), ff(50));

   GXDrawShape(aBitmapShape);
   GXDisposeShape(aBitmapShape);
}

Figure 5-27 compares the result of scaling the text shape with the result of scaling the bitmap shape.

Figure 5-27 Scaled text and a scaled bitmap

When scaling the text, QuickDraw GX uses the outline information in the font to draw the best representation of the text at the appropriate size. When scaling the bitmap representation of the text, QuickDraw GX simply scales the bits used to represent the smaller version of the text.

For more information about text shapes, see Inside Macintosh: QuickDraw GX Typography.

Clipping Bitmap Shapes

You can use the transform object of a bitmap shape to clip the bitmap--that is, restrict the area where QuickDraw GX draws the bitmap.

As an example, to apply a circular clip to the color ramp from Figure 5-24 on page 5-40, you start by defining the circular geometry and encapsulating it in a path shape:

long theClipGeometry[] = {1, 4, 0xF0000000, 
                          ff(50), ff(50),
                          ff(150), ff(50), 
                          ff(150), ff(150),
                          ff(50), ff(150)};
aClipShape = GXNewPaths((gxPaths *) theClipGeometry);

Then set the clip property of the bitmap's transform object by using this call to the GXSetShapeClip function:

GXSetShapeClip(aColorRampBitmapShape, aClipShape);

QuickDraw GX draws the resulting bitmap shape as shown in Figure 5-28. For a color version of this figure, see Plate 5 at the front of this book.

Figure 5-28 A clipped bitmap

For more information about transform objects, mapping transformations, clip shapes, and the GXSetShapeClip function, see the chapter "Transform Objects" in Inside Macintosh: QuickDraw GX Objects.